A client gets a dimension-mismatch error when inserting a point. What are the most common root causes?

A dimension-mismatch error means the vector you are sending does not have the same number of dimensions as the collection (or the specific named vector) expects. There are three common root causes and they are worth checking in this order because the first two are far more frequent than the third. The first is an embedding-model mismatch: the collection was created with the output dimension of model A (e.g. 768 for all-MiniLM-L6-v2) but the client is now using model B (e.g. 1536 for text-embedding-ada-002). This happens most often after a model upgrade, when the query path is updated but the ingest path, or the collection, is not. The second is a wrong named-vector target: the collection has multiple named vectors (e.g. title with 768 dims and body with 1536 dims), and the client sends a 1536-dim vector to the title field or omits the field name entirely and the client library routes it to the first field. The third is a collection created with the wrong vector size, which usually means the config was copied from another collection and not updated.

The mechanism is that vector size is a per-vector, immutable property of the collection. Qdrant validates the incoming vector's length against the declared size before storing it, and rejects the point if they do not match. There is no auto-detection, no padding, and no truncation. This is by design: a vector of the wrong size cannot be meaningfully compared with the stored vectors, so accepting it would corrupt the index. The error is immediate and unambiguous - it tells you the expected size and the received size - so the diagnosis is really about figuring out which of the three causes produced the mismatch. The first thing to check is the collection's actual vector configuration: call get_collection and read the size of each named vector. The second is to compare that with the dimension of the embedding model the client is actually using at that moment. The third is to verify that the client is specifying the correct named vector in the upsert call, because the error message alone does not tell you which field the vector was intended for.

The trade-off in fixing this is between a fast local fix and a correct long-term one. If the cause is a model mismatch, you cannot simply change the collection's size - vector size is immutable per vector, so a model change requires creating a new collection with the new size, re-embedding all points, and swapping an alias. That is the correct fix but it is expensive. If the cause is a wrong named-vector target, the fix is a one-line client change. If the cause is a wrong collection config, you rebuild the collection with the correct size. The common mistake is to try to patch the vector - truncating or padding it to make the error go away - which produces meaningless distances and silently degrades recall. The second mistake is to assume that all embedding models in the same family produce the same dimension; they do not, and switching between them without a re-index is a common cause of this error. The third mistake is to have different services using different models during a migration, which produces dimension errors intermittently depending on which service wrote the last point. Version note: the exact error message and the fields it includes have changed across Qdrant releases, but the root causes have not. The client API shape - specifically how a vector is associated with a named field - has changed with the query_points/upsert API in qdrant-client 1.10+.

Version-dependent: the vector size and distance metric are immutable per named vector in all recent Qdrant versions, so a model change always requires a new collection and re-embedding. The exact shape of the vectors config in the client response has changed across releases, and in some versions multi-vector collections require every named vector to be specified on upsert while in others partial specification is allowed. Read the effective collection config at runtime rather than assuming.